<html>
<head>
<title>RChart and JSP / Servlet</title>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
</head>

<body bgcolor="#FFFFFF" leftmargin="35">
<h3>RCHART, User Guide</h3>
<p><font face="Arial, Helvetica, sans-serif" size="-1"><i>Copyright 2007, J4L 
  Components (http://www.java4less.com)</i></font> <br>
  <a href="tutorialcontents.html">Go bak to contents</a> </p>
<hr>
<h3><font face="Arial, Helvetica, sans-serif">JSP and Servlet</font></h3>
<ul>
  <li><font face="Arial, Helvetica, sans-serif" size="-1"><a href="#0">Running 
    as servlet</a></font></li>
  <li><font face="Arial, Helvetica, sans-serif" size="-1"><a href="#1">Running 
    in JSP pages</a></font></li>
  <li><a href="plugins.htm"><font face="Arial, Helvetica, sans-serif" size="-1">Using 
    the RChart JSP Tag library</font></a></li>
  <li><a href="#4"><font face="Arial, Helvetica, sans-serif" size="-1">Interactive 
    web charts</font></a></li>
  <li><a href="#5"><font face="Arial, Helvetica, sans-serif" size="-1">Realtime 
    web charts</font></a><font face="Arial, Helvetica, sans-serif" size="-1"><br>
    </font></li>
  <li><font face="Arial, Helvetica, sans-serif" size="-1"><a href="#2">Unix and 
    Linux servers</a></font></li>
</ul>
<p>&nbsp;</p>
<p><font face="Arial, Helvetica, sans-serif" size="-1">While applets are small 
  Java programs that run in the browser (client), servlets and JSP pages are server 
  side programs which run in the web server and the output in GIF, PNG or JPEG 
  format is sent to the browser. RChart can run as servlet or inside JSP pages. 
  The product includes ready to use examples for both cases.</font></p>
<h4><font face="Arial, Helvetica, sans-serif" size="-1"><a name="0"></a>Running 
  as servlet</font></h4>
<p><font face="Arial, Helvetica, sans-serif" size="-1">The servlet class is called 
  <b>com.java4less.rchart.web.ChartServlet</b>. Basically you just need to call 
  the servlet and send the chart's parameters either using the GET or the POST 
  method. However the recommended way is using the DATAFILE parameter to tell 
  the servlet where it can get the parameters from (either from a file or a url). 
  <br>
  <br>
  In all cases the servlet supports 3 additional parameters:</font></p>
<ul>
  <li><font face="Arial, Helvetica, sans-serif" size="-1">WIDTH: width in pixels 
    of the output image. (default is 500). </font></li>
  <li><font face="Arial, Helvetica, sans-serif" size="-1">HEIGHT: height in pixels 
    of the output image. (default is 500). </font></li>
  <li><font face="Arial, Helvetica, sans-serif" size="-1">FORMAT: format of output 
    image, &quot;gif&quot;,</font><font face="Arial, Helvetica, sans-serif" size="-1"> 
    &quot;png&quot; or &quot;jpeg&quot;. (default is JPEG). <br>
    use the parameter DATAFILE if you want to read the chart definition from a 
    file. <br>
    Note: RChartServlet requires jdk 1.2 or newer. It is however possible to make 
    a jdk 1.1 compatible version.<br>
    <br>
    </font><font face="Arial, Helvetica, sans-serif" size="-1"> If you want to 
    create a PNG or GIF image you will need to download the encoder:</font></li>
</ul>
<ul>
  <ul>
    <li><font face="Arial, Helvetica, sans-serif" size="-1">PNG (by Walter Brameld 
      , wbrameld4@yahoo.com): download it from http://209.51.137.74/pngencoder-1.0.jar</font></li>
    <li><font face="Arial, Helvetica, sans-serif" size="-1">GIF: download gif 
      encoder from http://www.acme.com/resources/classes/Acme.tar.gz</font></li>
  </ul>
  <font face="Arial, Helvetica, sans-serif" size="-1"> </font> 
</ul>
<blockquote>
  <p><font face="Arial, Helvetica, sans-serif" size="-1"> </font></p>
</blockquote>
<p><font face="Arial, Helvetica, sans-serif" size="-1"><i><b>Example, Tomcat 5:</b></i><br>
  </font></p>
<p><font face="Arial, Helvetica, sans-serif" size="-1">In order to run the servlet 
  using Tomcat 5 you can follow these steps:</font></p>
<ol>
  <li><font size="-1" face="Arial, Helvetica, sans-serif"> create a new empty 
    directory for rchart in Tomcat: &quot;tomcatdirectory\webapps\rchart2&quot;</font></li>
  <li><font size="-1" face="Arial, Helvetica, sans-serif"> copy the file &quot;examples_servlet\web.xml&quot; 
    to &quot;tomcatdirectory\webapps\rchart2\WEB-INF\web.xml&quot;</font></li>
  <li><font size="-1" face="Arial, Helvetica, sans-serif"> copy the areaCurves.txt 
    file from the &quot;data\examples&quot; directory to &quot;tomcatdirectory\webapps\rchart2&quot;. 
    </font></li>
  <li><font size="-1" face="Arial, Helvetica, sans-serif"> Copy the image files 
    from the &quot;data&quot; directory to &quot;tomcatdirectory\webapps\rchart2\WEB-INF\classes&quot;. 
    This is only required if you want to view one of charts that uses a background 
    image. </font></li>
  <li><font size="-1" face="Arial, Helvetica, sans-serif"> copy bin\rchart2.jar 
    to &quot;tomcatdirectory\webapps\rchart2\WEB-INF\lib&quot;</font></li>
  <li><font size="-1" face="Arial, Helvetica, sans-serif"> start Tomcat</font></li>
  <li><font size="-1" face="Arial, Helvetica, sans-serif"> Open the following 
    URL in you browser:</font><br>
    <br>
    <font size="-1" face="Arial, Helvetica, sans-serif">http://localhost:8080/rchart2/servlet/RChartServlet?DATAFILE=http://localhost:8080/rchart2/areaCurves.txt</font><br>
    <br>
    <font size="-1" face="Arial, Helvetica, sans-serif">Note 1: if you want to 
    use the PNG or the GIF encoder you must copy the jar file to &quot;tomcatdirectory\webapps\rchart2\WEB-INF\lib&quot;</font></li>
</ol>
<p><font face="Arial, Helvetica, sans-serif" size="-1">If you have any problems 
  running the servlet check the following:</font></p>
<ul>
  <li><font face="Arial, Helvetica, sans-serif" size="-1">The servlet is actually 
    being executed, look in the java console or in the servlets logs if there 
    are messages written by the servlet.</font></li>
  <li><font face="Arial, Helvetica, sans-serif" size="-1">The data file can be 
    found. Enter &quot;http://localhost:8080/rchart2/areaCurves.txt&quot; in your 
    browser to check if it can be found.</font></li>
</ul>
<blockquote> 
  <blockquote> 
    <blockquote> 
      <p>&nbsp;</p>
    </blockquote>
  </blockquote>
</blockquote>
<h4><font face="Arial, Helvetica, sans-serif" size="-1"><a name="1"></a>Running 
  in JSP pages</font></h4>
<p><font face="Arial, Helvetica, sans-serif" size="-1">JSP pages are more flexible 
  than the ChartServlet but you need to deal with a bit of Java/JSP programming. 
  RChart however includes a small JSP application which can be used with none 
  or little modification. </font></p>
<p><font face="Arial, Helvetica, sans-serif" size="-1">A simple JSP page to display 
  a chart is:<br>
  </font></p>
<blockquote> 
  <blockquote>
    <p><font face="Courier New, Courier, mono" size="-1">&lt;%<br>
      String encode=&quot;jpeg&quot;;<br>
      String myurl=&quot;http://localhost:8080/rchart2/&quot;;<br>
      String dataFile=&quot;combined2Positions.txt&quot;;</font></p>
    <p><font face="Courier New, Courier, mono" size="-1">// set response headers<br>
      response.setContentType(&quot;image/&quot;+encode);<br>
      response.setDateHeader (&quot;Expires&quot;,0);</font></p>
    <p><font face="Courier New, Courier, mono" size="-1">// get output stream<br>
      java.io.OutputStream outb=response.getOutputStream();<br>
      <br>
      </font><font face="Courier New, Courier, mono" size="-1"> </font><font face="Courier New, Courier, mono" size="-1">// 
      create Chart from data file<br>
      com.java4less.rchart.ChartLoader loader=new com.java4less.rchart.ChartLoader();<br>
      loader.loadFromFile(myurl+dataFile,false);<br>
      com.java4less.rchart.Chart chart=loader.build(false,false);</font></p>
    <p><font face="Courier New, Courier, mono" size="-1">// set size of the chart<br>
      chart.setSize(500,500);</font></p>
    <p><font face="Courier New, Courier, mono" size="-1">// encode image and send 
      output to the browser<br>
      chart.saveToFile(outb,encode); <br>
      outb.close();<br>
      %&gt;</font></p>
  </blockquote>
</blockquote>
<p><font face="Arial, Helvetica, sans-serif" size="-1"><i><b>Example, Tomcat 5:</b></i></font><br>
  <br>
  <font face="Arial, Helvetica, sans-serif" size="-1">In order to run the JSP 
  examples using Tomcat 5 you can follow these steps:</font></p>
<ol>
  <li><font face="Arial, Helvetica, sans-serif" size="-1"> create a new empty 
    directory for rchart in tomcat: &quot;tomcatdirectory\webapps\rchart2&quot;</font></li>
  <li><font face="Arial, Helvetica, sans-serif" size="-1"> copy all files from 
    the &quot;data\examples&quot; directory to &quot;tomcatdirectory\webapps\rchart2&quot;. 
    </font></li>
  <li><font face="Arial, Helvetica, sans-serif" size="-1"> Copy all image files 
    from the &quot;data&quot; directory to &quot;tomcatdirectory\webapps\rchart2\WEB-INF\classes&quot;. 
    </font></li>
  <li><font face="Arial, Helvetica, sans-serif" size="-1"> copy bin\rchart2.jar 
    to &quot;tomcatdirectory\webapps\rchart2\WEB-INF\lib&quot;</font></li>
  <li><font face="Arial, Helvetica, sans-serif" size="-1"> start Tomcat</font></li>
  <li><font face="Arial, Helvetica, sans-serif" size="-1"> Open the following 
    URL in you browser:<br>
    <br>
    </font><font face="Arial, Helvetica, sans-serif" size="-1">http://localhost:8080/rchart2/Examples.htm<br>
    </font><font face="Arial, Helvetica, sans-serif" size="-1"><br>
    Note 1: if you want to use the PNG or the GIF encoder you must copy the jar 
    file to &quot;tomcatdirectory\webapps\rchart2\WEB-INF\lib&quot;and change 
    the following line in all JSP pages:<br>
    <br>
    </font><font face="Arial, Helvetica, sans-serif" size="-1">String encode=&quot;jpeg&quot;;</font></li>
</ol>
<p>&nbsp;</p>
<p><font face="Arial, Helvetica, sans-serif" size="-1"><b>Note:</b> You can also 
  use <a href="plugins.htm"> RChart JSP Tag library </a>to create charts without 
  any java code.</font></p>
<p>&nbsp;</p>
<h4><font face="Arial, Helvetica, sans-serif" size="-1"><a name="4"></a>Interactive 
  web charts</font></h4>
<p><font size="-1" face="Arial, Helvetica, sans-serif">RChart can create image 
  maps for the chart images which provides you with the following features:</font></p>
<ol>
  <li><font size="-1" face="Arial, Helvetica, sans-serif"> Tooltips are shown 
    when the mouse is placed over a bar or point.</font></li>
  <li><font size="-1" face="Arial, Helvetica, sans-serif">HTML links: a new html 
    link can be openned when the user click's on a point in the chart.</font></li>
  <li><font size="-1" face="Arial, Helvetica, sans-serif">Actions: for example 
    javascript functions can be executed when the user click's on a point in the 
    chart.</font></li>
</ol>
<p><font size="-1" face="Arial, Helvetica, sans-serif">The following parameters 
  are used for defining tips and links:</font></p>
<ul>
  <li><font size="-1" face="Arial, Helvetica, sans-serif">CHART_SHOW_TIPS. Set 
    it to &quot;true&quot; in order to activate tips. </font></li>
  <li><font size="-1" face="Arial, Helvetica, sans-serif">SERIE_TIPS_*: list of 
    tips for the values of the serie. For example, if serie 1 has 3 bars:<br>
    <br>
    SERIE_TIPS_1=tip for first bar|tip for second bar| tip for third bar <br>
    <br>
    </font></li>
  <li><font size="-1" face="Arial, Helvetica, sans-serif">SERE_POINT_1=true. Linecharts 
    require the points to be active. </font></li>
  <li><font size="-1" face="Arial, Helvetica, sans-serif">SERIE_LINKS_*: list 
    of html links, for example :<br>
    <br>
    http://www.server.com/value1.html|http://www.server.com/value2.html|http://www.server.com/value3.html 
    <br>
    <br>
    you can also execute javascript functions, for example:<br>
    <br>
    javascript:alert('hello world')<br>
    <br>
    </font></li>
  <li><font size="-1" face="Arial, Helvetica, sans-serif">CHART_LINKS_TARGET: 
    this is the frame or window where the html links should be openned (the default 
    value is _new)</font></li>
</ul>
<p><font size="-1" face="Arial, Helvetica, sans-serif"><br>
  In order to create a chart and its associate image map you need 2 servlets or 
  2 JSP pages. One of them is in charge of creating the chart's image and the 
  other is in charge of creating the image map.</font></p>
<p><font face="Arial, Helvetica, sans-serif" size="-1">You can use the html links 
  to open a subchart when the user clicks on a given point of the chart, in this 
  way you are creating drill-down charts.</font></p>
<p><font size="-1" face="Arial, Helvetica, sans-serif"><b><i>JSP pages</i></b></font></p>
<p><font face="Arial, Helvetica, sans-serif" size="-1">The following code creates 
  a chart and the image map. Note that the page itself only creates the HTML image 
  map and a IMG tag which calls a second JSP script that will deliver the JPEG 
  image (see &quot;examples_jsp&quot; directory).</font></p>
<blockquote>
  <blockquote> 
    <p>&nbsp;</p>
    <p><font face="Courier New, Courier, mono" size="-1">&lt;%<br>
      String encode=&quot;jpeg&quot;;<br>
      String myurl=&quot;http://localhost:8080/rchart2/&quot;;<br>
      String dataFile=&quot;combined2Positions.txt&quot;;<br>
      </font></p>
    <p><font face="Courier New, Courier, mono" size="-1">response.setContentType(&quot;text/html&quot;);<br>
      response.setDateHeader (&quot;Expires&quot;,0);</font></p>
    <p><font face="Courier New, Courier, mono" size="-1">// get output stream<br>
      java.io.PrintWriter outb=response.getWriter();</font></p>
    <p> <font face="Courier New, Courier, mono" size="-1">// create Chart from 
      data file<br>
      com.java4less.rchart.ChartLoader loader=new com.java4less.rchart.ChartLoader();<br>
      loader.loadFromFile(myurl+dataFile,false);<br>
      com.java4less.rchart.Chart chart=loader.build(false,false);</font></p>
    <p><font face="Courier New, Courier, mono" size="-1">// set size of the chart<br>
      chart.setSize(w,h);</font></p>
    <p><font face="Courier New, Courier, mono" size="-1">// we must paint the 
      chart once before we can retrieve the image map<br>
      com.java4less.rchart.gc.ChartImage chartImage= com.java4less.rchart.gc.GraphicsProvider.createImage(w,h);<br>
      com.java4less.rchart.gc.ChartGraphics chartGraphics=chartImage.getGraphics();<br>
      chart.paint(chartGraphics);<br>
      chartGraphics.dispose();<br>
      chartImage.dispose();</font></p>
    <p><font face="Courier New, Courier, mono" size="-1"><br>
      // retrieve image map<br>
      String htmlMap=chart.getHTMLImageMap(&quot;Chart&quot;);</font></p>
    <p><font face="Courier New, Courier, mono" size="-1">// html output<br>
      outb.print(&quot;&lt;html&gt;&quot;); <br>
      outb.print(&quot;&lt;body&gt;&quot;);<br>
      // IMG tag which includes the link to the second JSP page<br>
      </font><font face="Courier New, Courier, mono" size="-1">outb.print(&quot;&lt;img 
      src='getChart.jsp?chart=&quot;+dataFile+&quot;' BORDER=0 NAME='ICHART' USEMAP='#Chart'&gt;&quot;);<br>
      // output image map now<br>
      outb.print(htmlMap); <br>
      outb.print(&quot;&lt;/body&gt;&quot;);<br>
      outb.print(&quot;&lt;/html&gt;&quot;);</font></p>
    <p><font face="Courier New, Courier, mono" size="-1"><br>
      outb.close();<br>
      %&gt;</font></p>
  </blockquote>
</blockquote>
<p>&nbsp;</p>
<p><font size="-1" face="Arial, Helvetica, sans-serif"><b><i>Servlet</i></b></font></p>
<p><font face="Arial, Helvetica, sans-serif" size="-1">RChart only includes a 
  servlet which can create image maps. The name of the servlet is <b>com.java4less.rchart.web.ChartMapServlet</b> 
  and must be used in the same way as the ChartServlet. Note that he ChartMapServlet 
  creates the image map only, not the image itself.</font></p>
<p>&nbsp;</p>
<h4><font face="Arial, Helvetica, sans-serif" size="-1"><a name="5"></a>Realtime 
  web charts</font></h4>
<p><font face="Arial, Helvetica, sans-serif" size="-1">In some applications you 
  need the chart to be continuosly be updated with new data. The following two 
  files in the &quot;examples_jsp&quot; directory shows you how to do it:</font></p>
<ul>
  <li><font face="Arial, Helvetica, sans-serif" size="-1"> getDynamicChart.jsp: 
    this file creates a new chart each time it is called. It creates a chart with 
    new data based on the time in your computer, so the data will keep on changing.</font></li>
  <li><font face="Arial, Helvetica, sans-serif" size="-1">getRealtimeChart.jsp: 
    this is the main file. It includes a link to the getDynamicChart.jsp and a 
    small javascript program that will regularly refresh the image.<br>
    </font> 
    <blockquote> 
      <p>&nbsp;</p>
    </blockquote>
  </li>
</ul>
<p><font face="Arial, Helvetica, sans-serif" size="-1">Note that the browser must 
  be Javascript enabled to support this feature. The Javascript function for refreshing 
  the chart is very simple:</font> </p>
<ul>
  <blockquote>
    <p><font face="Arial, Helvetica, sans-serif" size="-1"> <font face="Courier New, Courier, mono">function 
      refreshChart(){</font></font></p>
    <p><font face="Courier New, Courier, mono" size="-1"> document.ICHART.src='getDynamicChart.jsp';</font></p>
    <p><font face="Courier New, Courier, mono" size="-1"> setTimeout(&quot;refreshChart()&quot;,3000);</font></p>
    <p><font face="Courier New, Courier, mono" size="-1"> }</font></p>
  </blockquote>
</ul>
<p><font face="Arial, Helvetica, sans-serif" size="-1"><br>
  the function calls itself every 5 seconds and reload the image called ICHART. 
  The image is defined as:</font></p>
<blockquote>
  <p><font face="Courier New, Courier, mono" size="-1">&lt;img src='getDynamicChart.jsp' 
    BORDER=0 NAME='ICHART'&gt;</font> </p>
</blockquote>
<p>&nbsp;</p>
<h4><font face="Arial, Helvetica, sans-serif" size="-1"><a name="2"></a>Unix and 
  Linux servers</font></h4>
<p><font face="Arial, Helvetica, sans-serif" size="-1">If you run RChart on a 
  Unix or Linux server you must take into account the following. Java graphics 
  classes require a X11 server to be running. This is a well known java problem.</font></p>
<p><font face="Arial, Helvetica, sans-serif" size="-1">If you are not running 
  a X11 server you will get errors like:</font></p>
<blockquote> 
  <blockquote> 
    <p> <font face="Arial, Helvetica, sans-serif" size="-1"><i>Exception java.lang.NoClassDefFoundError<br>
      at java.lang.Class.forName0(Native Method) at java.lang.Class.forName(Class.java:120) 
      <br>
      at java.awt.GraphicsEnvironment.getLocalGraphicsEnvironment (GraphicsEnvironment.java:58)<br>
      .... </i></font></p>
  </blockquote>
</blockquote>
<p><font face="Arial, Helvetica, sans-serif" size="-1">or</font></p>
<blockquote> 
  <blockquote> 
    <p><font face="Arial, Helvetica, sans-serif" size="-1"><i>java.lang.InternalError: 
      Can't connect to X11 window server using ':0.0' as the value of the DISPLAY 
      variable. at sun.awt.X11GraphicsEnvironment.initDisplay(Native Method)<br>
      .</i></font></p>
  </blockquote>
</blockquote>
<p><font face="Arial, Helvetica, sans-serif" size="-1">or similar.<br>
  <br>
  The most common solutions to this problem are:</font></p>
<ul>
  <li><font face="Arial, Helvetica, sans-serif" size="-1">If you run Java 1.4 
    or later you can use java in headless mode. This is done by starting the java 
    machine with the &quot;-Djava.awt.headless=true&quot; parameter.</font></li>
  <li><font face="Arial, Helvetica, sans-serif" size="-1">If you run Java 1.1, 
    1.2 or 1.3 you can install a dummy X server, such as the Xvfb utility.</font></li>
</ul>
<hr>
<p><font face="Arial, Helvetica, sans-serif" size="-1"></font></p>
<p>&nbsp;</p>
</body>
</html>
